Initial commit of the ‘Hello, Scala’ book contents #1423
Conversation
… the book contents under the Learn menu as an initial starting point.
|
Thanks a lot @alvinj! Unfortunately I'm about to go on vacation for three weeks, do I won't have time to look at this before the end of July. Others will probably give their input first. |
|
This is great!! Somehow, the current page is not highlighted in the navigation, at least on my preview. It works for other tutorials that we have, like "Tour of Scala". There should also be a box for the book on the landing page, if it's only in the menu it's not visible enough. |
There was a problem hiding this comment.
Thanks @alvinj!
Overall, the outline looks good to me. I’m wondering if we should keep the part about Akka? These examples are already a bit outdated, and Akka seems a bit too specific to me, I think the docs.scala-lang.org should focus on more general things. We might want to have a link to the Akka website, though.
@lrytz Indeed, it seems that the “multipage-overview” layout does not highlight the current page. We should copy what has been done in the “tour” layout to highlight the current page in the TOC. We should also add support for “Next page” and “Previous page” links. (But all of that could be done in separate PRs)
| @@ -18,6 +18,8 @@ | |||
| url: "/tutorials/scala-for-java-programmers.html" | |||
| - title: Online Resources | |||
| url: "/learn.html" | |||
| - title: “Hello, Scala” Book | |||
| url: "/overviews/hello-scala/introduction.html" | |||
There was a problem hiding this comment.
I would put this item higher on the menu. Just after the “Tour of Scala”, for instance. Also, I would remove the /overviews segment from the URL (just move the hello-scala directory to its grand-parent directory). “Overviews” are usually in the “Guides & Overviews” menu. (I know I’ve first suggested to put “Hello, Scala” in the overviews, but now I think it’s better to have it in the “Learn” menu).
Also, what do you think of just naming this item “Hello, Scala”? I don’t think we should have the “Book” suffix at least.
There was a problem hiding this comment.
Yes, I can move the link higher. I thought there might be some discussion about where to put it, so I started with it at the bottom.
I’ll also move the hello-scala directory up.
I added the “Book” part because I thought “Hello, Scala” in the menu looked a little strange on its own. I couldn’t think of a better way to show that this is a book. But I’ll remove it, and also remove the quotes around the Hello, Scala title.
There was a problem hiding this comment.
@julienrf I may have misread what you wrote. Are you going to change the “multipage-overview” layout formatting, or should I use the “tour” layout? Thanks! (Or if you want I can see if I can figure out the “multipage-overview” layout.)
There was a problem hiding this comment.
@julienrf I can also remove the Akka lessons, and put a link to the Akka website at the end of the Futures lesson.
There was a problem hiding this comment.
Are you going to change the “multipage-overview” layout formatting, or should I use the “tour” layout?
Actually, I’m not sure! My reasoning was that anyway having working “next page”/“previous page” and current page highlight in the TOC would be beneficial to other multipage overviews, so we should anyway improve that layout. I’m not sure we can easily reuse the “tour” layout without breaking things because it has been designed specifically for the Tour.
There was a problem hiding this comment.
I think that the “multipage-overview” layout doesn’t work when the hello-scala directory is directly under the root directory. I’m pretty sure that’s the case, but I could be wrong.
Haha, that’s the joy of working with an untyped system 😂
Then I suggest that you leave everything under the overview/ directory, and focus on the content of the guide.
my initial thought was to create a new “book” layout, but it sounds like we all want next/previous links and a TOC that highlights the current page
That’s what I think too. I will take some time to improve the “multipage-overview” layout so that the current page is highlighted in the TOC, and we can have links between pages.
There was a problem hiding this comment.
Okay, sounds good, I’ll work on the content. Thanks again!
There was a problem hiding this comment.
No, I ended up not doing anything there. (When I used the Tour layout, the next/previous links worked, but everything stopped working when I moved the book content to the root directory, so I never tried to integrate that into the multipage-overview.)
There was a problem hiding this comment.
OK, I’ve created #1440 to support links between pages of an overview.
|
Just wanna drop by and say this is amazing, great work 😍 |
|
Hello @alvinj, do you still plan to work on this? Is there a way we can help? |
|
Hi Julien, I’m sorry for the delay. Yes, I’m still working on the book, but I can only give it about four hours a week, so progress is slow. I have removed almost every reference to my website, and I’ve been working on removing all of the I/my/me references in the book. I can submit a new pull request with the updated contents on Wednesday if you’d like. Two questions about that:
Thanks, |
|
Thanks for your message!
Alternatively, you can just push your new commits to your branch and this PR will be automatically updated. If you prefer creating a new PR, I suggest that you first create a separate branch rather than working on
I think so, we can figure out later how to move it to a different directory if needed.
Yes! All the issues we’ve seen before should have been fixed now. You can also define Let me know if you have any other question! |
|
Okay, that all sounds great. One way or another I’ll try to commit the latest changes on Wednesday. Thanks again! |
|
Okay, I rearranged my schedule a bit to fast-track this. Unfortunately I couldn’t figure out what I did to my original fork and this PR, so I created a new fork and new PR. Sorry about that part, but that PR explains the changes, and I think my branching skills are getting a little better. :) |
|
No worries, thanks a lot for your work! I’m closing this PR in favor of #1469. |
I haven’t submitted a pull request in a while, so I hope I did this properly. (If not, just let me know.) My changes are in a branch named hello_scala.
I made two main changes:
Also please note:
Also, there is one link to the printed book on Amazon in the last chapter. I left that in there in case anyone wants a printed version of the book, but of course it can be removed. My hope/plan is to follow other models where the website version of the book and the corresponding PDF are free, and a printed version of the book is also available.